/*
 * Copyright (c) 2009, 2013, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package java.lang;

/**
 * 一个可以保存资源(如文件或套接字句柄)直到它关闭的对象。
 * 当退出一个try-with-resources块时，AutoCloseable对象的close()方法
 * 将被自动调用，该对象已经在资源规范头中声明。
 * 这种构造确保了及时的释放，避免了资源耗尽异常和可能发生的错误。
 *
 * <p>基类实现AutoCloseable是可能的，实际上也是很常见的，即使不是它的所有子类或实例都拥有可释放的资源。
 * 对于必须完全通用地操作的代码，或者当大家都知道是AutoCloseable实例需要资源释放时，建议使用try-with-resources结构。
 * 但是，在使用诸如java.util.stream这样的，同时支持基于IO与基于非IO的形式，
 * 当使用基于非IO的形式时，就没有必要尝试try-with-resources结构。
 *
 * @author Josh Bloch
 * @since 1.7
 */
public interface AutoCloseable {
    /**
     * 关闭此资源，放弃任何底层资源。
     * 此方法在try-with-resources语句管理的对象上自动调用。
     *
     * <p>虽然这个接口方法被声明为抛出异常，但是强烈建议实现者声明close方法的具体
     * 实现来抛出更具体的异常，或者如果close操作不会失败，完全不抛出任何异常。
     *
     * <p> 在关闭操作可能失败的情况下，实现者需要格外注意。
     * 强烈建议在抛出异常之前，放弃底层资源并在内部将元素标记为closed。
     * close方法不太可能被多次调用，因此这确保了资源被及时释放。
     * 此外，它还减少了当资源包裹或被另一个资源包裹时可能出现的问题。
     *
     * <p>强烈建议此接口的实现者不要让close方法抛出InterruptedException。
     * 此异常与线程的interrupted状态交互，如果抑制InterruptedException，则很可能发生运行时错误行为。
     * 更一般地，如果它会导致一个会被抑制的异常，则AutoCloseable.close不应该抛出它。
     *
     * <p>注意，这与java.io.Closeable的close方法不同。可闭性，这种封闭方法不需要是幂等的。
     * 换句话说，与Closeable不同，多次调用这个close方法可能会产生一些明显的副作用。
     * Closeable.close，如果多次调用，则必须没有效果。
     * 但是，强烈鼓励该接口的实现者使其close方法幂等。
     *
     * @throws Exception 如果资源不能被关闭
     */
    void close() throws Exception;
}
